Skip to content

feat(gateway): wire the Wave 7 enterprise features together - #76

Merged
ALikesToCode merged 25 commits into
integrate/gateway-waves-1-6from
integrate/gateway-waves-1-7
Oct 9, 2026
Merged

ALikesToCode merged 25 commits into
integrate/gateway-waves-1-6from
integrate/gateway-waves-1-7

Conversation

@ALikesToCode

@ALikesToCode ALikesToCode commented Oct 9, 2026 •

Copy link
Copy Markdown
Owner

Summary

This branch merges all six Wave 7 feature branches on top of the Wave 6 integration branch (#69) and wires them together. It is based on integrate/gateway-waves-1-6, so this diff shows only Wave 7.

PR Feature Settings
#70 Organisations and teams ORGANISATIONS_ENABLED, migration 0033
#71 Tenant governance TENANT_GOVERNANCE_ENABLED, migration 0034
#72 SAML federation SAML_ENABLED, SAML_BROKER_URL, SAML_TRUST_CONFIG_JSON, SAML_CALLBACK_URL, migration 0035
#73 SCIM provisioning SCIM_ENABLED, SCIM_TRUST_CONFIG_JSON, migration 0036
#74 Credits ledger CREDITS_ENABLED, CREDITS_CURRENCY, migration 0037
#75 Payment billing PAYMENTS_ENABLED, PAYMENT_PROCESSOR_CONFIG_JSON, PAYMENT_WEBHOOK_KEY_REF, migration 0038

The six PRs form one stack (#70 → #75) so each keeps its migration numbering contiguous. This branch adds one new setting, CREDITS_ENFORCEMENT. With every Wave 7 setting unset, requests, responses, cache keys, idempotency fingerprints, storage owners and logs are unchanged; the tests below check this.

Decisions

These choices go beyond the individual features:

  • One owner. The workspace comes only from the post-authentication tenant hook. Governance, SCIM, SAML, credits and payments read that same verified context. A payment checkout, GET /v1/credits and a charged request all use the same credits owner. That owner is the principal within the selected workspace, so a billing member's top-up funds that member's own usage in that workspace, not the whole organisation's.
  • Requests are charged only on request. CREDITS_ENABLED=true turns on the ledger, its routes and payment credits; on its own it charges nothing. CREDITS_ENFORCEMENT:
    • off (the default) charges no request;
    • funded charges owners who have ever received a credit or adjustment;
    • all charges every authenticated owner, administrators included.
  • Credit errors. Not enough credit returns 402 credits_insufficient before dispatch. An unpriced charged request returns 503 credits_unpriced.
  • Refunds and disputes. These are recorded as negative adjust entries with a reserved processor: actor, and they apply even when the credit was already spent. The balance can then go negative, and new reservations are refused until it is covered. Only the payment webhook path can write these entries; the admin adjust route rejects that actor. No migration is needed, since 0037 already allows adjust.
  • Where denials happen. Credit and governance denials happen at the same point as today's key-budget denial: after the idempotency claim and admission. A denied request reaches no provider and leaves no open hold. A client retrying after a top-up needs a new Idempotency-Key.

Integration changes

Flask

  • app.py mounts the SAML, SCIM, credits and payment routes.

    • Each disabled feature answers 404 before authentication.
    • The core login guard lets the SAML endpoints, SCIM bearer-token endpoints and the payment webhook through; each still authenticates itself.
  • The enterprise adapters are built once: the tenant authority (organisations), the SAML identity authority, the credits authority with the gateway's price table as its tariff, and the payment callback. The preview route no longer replaces them, whatever the registration order.

  • Governance: its grants and roles come from the organisation memberships.

  • SAML login: it issues the same dashboard session as a password login, through a small function extracted from AuthService.authenticate_user. That function re-checks that the account is active and unexpired.

  • Private storage endpoints: tenant_governance, saml, scim, credits and payments, each with its handler's request bound.

  • Reservations:

    1. The key budget and governance reserve first.
    2. Credits reserve last.
    3. A refusal before dispatch releases both holds once.
    4. Measured cost commits.
    5. An unknown cost keeps the hold.

    Hedged attempts and gateway subrequests (cascades, image QA) get their own reservation. An operator reconciliation with a known cost settles the governance and credits holds once, keyed by the immutable transition ID.

  • Workspace separation: with organisations on, the exact, shared and semantic cache keys, idempotency fingerprints, hosted Responses owners, context pages and usage rows include the workspace. A legacy (unbound) caller's key keeps exactly today's bytes.

  • Background jobs: media and gateway batch jobs carry the verified workspace in their signed capability and never resolve it again later.

  • Payment webhook: it verifies the exact raw bytes it received, with every Wave 1–7 feature on.

Worker

  • Private routes: /v1/tenant-governance, plus /v1/managed-state/saml, scim, credits and payments. A SCIM user or group change commits together with its account, membership and team rows in one batch.
  • Native generations:
    • The workspace is resolved only for the principal whose key matched.
    • Governance and credits run inside the reservation lifecycle with the same order and error statuses as Flask.
    • Semantic-cache embeddings and generations reserve separately.
    • A cache hit releases the generation estimate.
  • Workspace separation: exact and semantic cache keys, idempotency claims, Responses state, context pages and native usage rows include the workspace only when one is bound.
  • Realtime, the payment webhook, SCIM and SAML keep forwarding exactly as before.

Registrations

  • CREDITS_ENFORCEMENT in the Container env keys.
  • ETag exposed and If-Match allowed in both CORS lists, for the revision-checked admin and SCIM APIs.
  • tests/test_wave7_worker.mjs in test:worker.
  • worker/credits-admission.mjs in the edge module inventory.
  • Six README lines.

Review fixes during integration

  • Deadline hook. An earlier version skipped the native generation setup whenever organisations were on, which silently dropped the X-MultiLLM-Deadline-Ms deadline. Setup now runs as before.

  • Account names that aren't opaque IDs. For a name such as [email protected], the tenant module uses a hashed principal ID, but four checks compared it with the raw name:

    • governance would have refused every request from such an account;
    • their budget owner would have skipped the workspace;
    • their batch submissions would have returned 503.

    A shared principal_id() helper now makes all four agree, and a regression test covers it.

  • SQLite membership writes. These checked that the account exists inside the write transaction, which could hit "database is locked" on the account database. The check now runs first.

Before merging to main

Six D1 migrations are included, 0033_tenant_hierarchy.sql through 0038_payment_billing.sql. A push to main does not apply them, so apply them first:

npx wrangler d1 migrations apply multillm-intelligence --remote

Every one only adds tables and indexes. Before enabling:

  • Credit owners first: fund owners before choosing CREDITS_ENFORCEMENT=all.
  • SCIM storage: SCIM needs AUTH_STORAGE_BACKEND=d1, INTELLIGENCE_STORAGE_BACKEND=d1 and CONFIG_REVISION_SYNC_ENABLED=true.
  • Webhook events: select exactly the five Stripe event types in docs/payment-billing.md on the webhook endpoint, and rehearse the flow in the Stripe sandbox.

Known limits

  • services/auth_service.py is 1,252 lines; it only gained the extracted session function. Splitting out session handling is the natural next step.
  • SAML login is Flask-only. The Worker's native ACS and metadata routes return 503 saml_native_unavailable, as documented.
  • A dispute that the merchant later wins is not credited back automatically; an operator adjusts it.
  • Credits and governance estimates come from the gateway's price table and are not provider invoices.

Tests

  • New tests:
    • tests/test_wave7_registrar.py: mounting, SAML session issuance, SCIM, credits, payments, processor entries and the webhook bytes;
    • tests/test_wave7_managed.py: credit and governance admission, release, commit and reconcile, hedged and subrequest attempts, and workspace separation;
    • tests/test_wave7_worker.mjs: private routes, native admission order, SCIM batches and workspace keys;
    • shared governance reconciliation vectors in tests/fixtures/governance_reconciliation.json.
  • They cover:
    • every Wave 7 setting off, byte for byte;
    • each feature alone;
    • every setting on.
  • Full Python suite: 5,047 passed, 2 skipped. ruff, mypy and bandit are clean.
  • npm run test:worker: 1,890 passed. npm run test:integration: 7 passed.
  • cf:migrations:check reports 38 contiguous, additive migrations. test:deploy, free routes, client headers and the wrangler deploy --dry-run bundle all pass.
  • tests/test_frontend_build.mjs fails locally because @tailwindcss/cli is not installed. It fails the same way on main.

CI notes

  • GitHub python/node jobs: the dependency-audit fix (fix(deps): clear the CI dependency audit advisories #42) is now merged into the bottom of the chain and up every layer. The audits pass, and the full Python and Worker suites run in CI and pass on every integration branch.
  • First full CI runs: these found tests that only passed on the development machine. They are fixed at the layer that introduced each test:
    • four tests started a Python interpreter by absolute local path; they now use PYTHON, .venv or python3, and the node job installs the locked Python dependencies;
    • three timing bounds were too tight for shared runners.
  • Workers Builds: fails on this stack because the Wave 3 base adds the AdmissionCoordinator Durable Object migration, which wrangler versions upload cannot apply. This is expected until wrangler deploy runs on main.

SAML_ENABLED (off by default) adds broker-backed dashboard login. The gateway
never parses SAML XML: an operator-run broker returns a compact JWS that is
verified against pinned RS256 or Ed25519 keys and bound to the issuer,
audience, recipient, nonce and browser state. Each request nonce is claimed
once, and only an operator-created subject link maps a verified subject to an
existing account, with no just-in-time accounts or administrator grants.

Native ACS and metadata return 503 saml_native_unavailable. Request state,
subject links and audit rows live in D1 (migration 0035).
…webhooks

PAYMENTS_ENABLED (off by default) adds POST /v1/payments/checkout, which
creates a Stripe Checkout Session for a whole-cent USD amount between $0.50
and $1,000 from an allowlisted return origin, with per-principal daily limits
and idempotent replay. POST /v1/payments/webhook verifies the raw body's v1
signature and timestamp, claims each event before any callback, and checks
livemode, merchant, currency, amount and session against the stored checkout.

Credits are added only through the injected payment callback, once per
checkout; refunds and disputes append compensation. The browser return page
never credits. Configuration holds secret references only (migration 0038).
SCIM_ENABLED (off by default) serves /scim/v2 discovery, Users and Groups with
SCIM errors, ETag versions and If-Match checks, count-bounded pagination and a
small documented filter subset. A provisioning bearer token is matched by
digest against tenant-scoped secret references, and fixes the organisation.

Provisioned accounts are never administrators and receive no usable key over
SCIM. Deactivation or deletion revokes the account's key and sessions through
the security revision and keeps the account, external identity and usage.
Groups map to teams through the tenant authority. Storage is in D1
(migration 0036).
CREDITS_ENABLED (off by default) keeps an append-only integer micro-USD ledger
per owner: credit, reserve, commit, release, adjust and compensate entries,
each idempotent by operation ID and written with a compare-and-swap on the
owner's balance revision. Corrections append compensation entries and never
rewrite history.

Reservations and negative adjustments may not make available credit
negative. A commit always records the actual cost and closes its hold, so an
overrun leaves available credit negative and new reservations are refused
until credits cover it. An unknown cost keeps the hold.

GET /v1/credits returns the owner's balance and paged entries, and
POST /admin/credits/adjust needs an administrator session and If-Match. The
ledger implements the enterprise CreditAuthority; connecting it to request
reservations comes with integration (migration 0037).
…tion

TENANT_GOVERNANCE_ENABLED (off by default) applies organisation and team
policies to requests in a verified workspace. Model and tool grants
intersect with the key's own grants and never widen them. Budgets at every
configured level, plus the key's own limits, are reserved together in one
atomic operation and settled together; an over-limit level denies the
request before dispatch, and an unknown cost keeps its hold at every level.

Roles come from a static permission table. Administrators edit policies
through /admin/organisations/<org_id>[/teams/<team_id>]/governance with
If-Match and audit rows, and /v1/usage gains a workspace breakdown for
callers in a workspace. Requests outside a workspace are unchanged
(migration 0034).
ORGANISATIONS_ENABLED (off by default) adds a two-level organisation and team
hierarchy with stable opaque IDs, roles, caps and deactivation instead of
deletion. Administrators manage it under /admin/organisations with
If-Match revisions and audit rows. Each account has at most one server-side
workspace binding; /v1/workspaces lists the caller's memberships and
/v1/workspaces/switch changes the binding only after a membership check.

A new first post-authentication hook resolves the verified TenantContext and
refuses a missing or deactivated workspace with 404 or 403 before any
storage, cache, claim or provider call. Caller headers never choose a
workspace. Native Worker generations, knowledge and Realtime resolve the
same context, only after the key matches. Accounts without a binding stay
in the legacy namespace (migration 0033).
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@coderabbitai

coderabbitai Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 695dce9a-9644-40d4-8c4d-4ea5eacd2ad3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
❌ Deployment failed
View logs
multillm-proxy 27c5f1d Oct 09 2026, 10:02 AM

@ALikesToCode
ALikesToCode merged commit 546cd41 into integrate/gateway-waves-1-6 Oct 9, 2026
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant